home *** CD-ROM | disk | FTP | other *** search
/ Apple WWDC 1996 / WWDC96_1996 (CD).toast / Technology Materials / MacOS 8 Resources / Developer Tools / Mac OS 8 Interfaces & Libraries / Interfaces / IDLIncludes / DebuggerSupport.idl < prev    next >
Text File  |  1996-05-01  |  12KB  |  223 lines
  1. /*
  2.      File:        DebuggerSupport.idl
  3.  
  4.      Contains:    Public interface to kernel services for debuggers
  5.  
  6.      Version:    Technology:    System 8
  7.                  Release:    Universal Interfaces 3.0d3 on Copland DR1
  8.  
  9.      Copyright:    © 1984-1996 by Apple Computer, Inc.  All rights reserved.
  10.  
  11.      Bugs?:        If you find a problem with this file, send the file and version
  12.                  information (from above) and the problem description to:
  13.  
  14.                      Internet:    apple.bugs@applelink.apple.com
  15.                      AppleLink:    APPLE.BUGS
  16.  
  17. */
  18. #ifndef __DEBUGGERSUPPORT_IDL__
  19. #define __DEBUGGERSUPPORT_IDL__
  20.  
  21. #include <somobj.idl>
  22. #include <somcls.idl>
  23.  
  24. #ifndef __TYPES_IDL__
  25. #include <Types.idl>
  26. #endif
  27. #ifndef __KERNEL_IDL__
  28. #include <Kernel.idl>
  29. #endif
  30. #ifndef __MACHINEEXCEPTIONS_IDL__
  31. #include <MachineExceptions.idl>
  32. #endif
  33.  
  34. #ifdef __SOMIDL__
  35.  
  36. #if FOR_SYSTEM8_PREEMPTIVE
  37. /*
  38.  In addition to the normal kernel API, the kernel provides a set of services
  39.  which are specific to debuggers.  These services are all accessed through the
  40.  DebuggerSupport library.
  41.  This first service is debugger registration and unregistration.  For a debugger
  42.  to register itself with the kernel, it calls DSRegisterDebugger.  (The kernel
  43.  allows only one registered debugger; multiple debuggers can be supported
  44.  externally by registering a dispatching entity as the debugger.)  When a debugger
  45.  has successfully registered itself, it is able to receive exceptions from
  46.  debuggable tasks.  Unregistering is simply the reverse of registering.  The
  47.  kernel automatically unregisters a debugger when it terminates if the debugger
  48.  has not already unregistered itself.  DSRegisterDebugger should be the first
  49.  call made to this library.
  50.  To receive an exception, the debugger calls DSWaitForException, passing it a
  51.  pointer to a DSExceptionRecord and a time limit.  This call blocks until either
  52.  an exception arrives or the time limit expires (pass kDurationForever to wait
  53.  indefinitely).  Note that this semantic essentially requires the debugger to
  54.  be multithreaded.
  55.  A DSExceptionRecord contains the ID of the excepted task, along with the IDs
  56.  of the task's team and address space, and a message ID corresponding to the
  57.  particular exception.  The details of the exception are contained in the
  58.  exception record's ExceptionInformation structure, which includes pointers
  59.  to the task's registers and other exception state.  The debugger may directly
  60.  modify this exception data, and, within limits, these changes will be forced
  61.  into the task's state upon resuming execution.  (Changes to certain parts of
  62.  the exception data, such as the privileged and interrupt enable bits of the
  63.  exception MSR, will be ignored.)
  64.  DSResumeFromException is used to resume the excepted task's execution or to
  65.  propagate the exception on.  It takes as parameters the exception ID and an
  66.  exception return status.  The status may be either noErr or any nonzero error
  67.  code.  noErr signifies that the debugger has cured the exception and the excepted
  68.  task should continue execution, using the state from the exception data.  Any
  69.  other status value will cause the exception to be propagated to the installed
  70.  exception handler, if any.  If there is no installed handler, or if that handler
  71.  fails to cure the exception, the exception is again presented to the debugger in
  72.  another message.  This time, returning a nonzero return status will cause the
  73.  task to be terminated.  (Double notification of exceptions allows a debugger to
  74.  catch exceptions either first, last, or at both times.)
  75.  Not all exceptions will be sent to the debugger.  Exceptions in kernel tasks
  76.  or in kernel code which runs on behalf of user tasks is not debuggable through
  77.  normal means.  Furthermore, exceptions occurring in privileged tasks with
  78.  hardware interrupts disabled, or during execution at secondary interrupt level,
  79.  or while running message system Accept functions, fall into the same category
  80.  as kernel exceptions and are not sent to the debugger.
  81.  The debugger may call DSHoldTasks to request the kernel to hold a task or set
  82.  of tasks, making them ineligible for execution.  The tasks are specified with a
  83.  task ID and scope (task only, task and children, task family, or task team).  If
  84.  any task to be held is already blocked inside the kernel, e.g. due to a page
  85.  fault, I/O operation, or message send, holding it will cause it to remain
  86.  ineligible even after it has unblocked.  Releasing held tasks with DSReleaseTasks
  87.  allows them to become eligible again.
  88.  DSGetTaskState is used to determine a task's scheduler state (runnable or blocked),
  89.  and, if blocked, what its PC and SP values were at the point it blocked.  If a
  90.  task is running a software interrupt it will have scheduler state for both its
  91.  normal execution and the execution of the software interrupt.
  92.  DSReadMemory and DSWriteMemory are used to access task memory.  To read memory,
  93.  the debugger simply calls DSReadMemory.  To modify memory, the debugger must first
  94.  call DSCreateMemoryAccess to obtain a memory write access right to the desired page
  95.  of memory.  Using that access right, it may then call DSWriteMemory to perform the
  96.  modification.  DSWriteMemory performs appropriate processor cache synchronization and
  97.  backing storage coordination to support modifying code memory, e.g. for instruction
  98.  breakpoints.  DSDeleteMemoryAccess is used to release an access right.
  99.  Some implementations of the kernel and hardware may support data breakpoints.  To
  100.  find out what data breakpoint support (if any) is available, the debugger calls
  101.  DSGetDataBreakpointInformation.  DSSetDataBreakpoint is used to set or clear a
  102.  data breakpoint.  The implementation may cause excess exceptions which will have to
  103.  be filtered out by the debugger:  breakpoints may occur in the wrong address space
  104.  or on an address which is outside the range specified but which lies within the
  105.  resolution range supported by the implementation.
  106.  Exception notification record
  107. */
  108. typedef SOMLargeStruct            DSExceptionRecord;            /* Derived from a struct of 36 bytes in size */
  109.  
  110. typedef OpaquePtr                DSExceptionRecordPtr;        /* Substituted OpaquePtr for ``DSExceptionRecord*'' */
  111.  
  112. /* Task state record*/
  113. typedef SOMLargeStruct            DSKernelState;                /* Derived from a struct of 12 bytes in size */
  114.  
  115. typedef OpaquePtr                DSKernelStatePtr;            /* Substituted OpaquePtr for ``DSKernelState*'' */
  116.  
  117. typedef SOMLargeStruct            DSTaskState;                /* Derived from a struct of 24 bytes in size */
  118.  
  119. typedef OpaquePtr                DSTaskStatePtr;                /* Substituted OpaquePtr for ``DSTaskState*'' */
  120.  
  121. /* ID to specify write access rights to a particular page in logical memory*/
  122. typedef OpaquePtr                DSMemoryAccessID;
  123.  
  124. /* SchedulerState values*/
  125. /*
  126.  Describes the data breakpoint facility provided by the current implementation.
  127.  maxBreakpoints is the maximum number of data breakpoints available (may be zero).
  128.  breakpointResolution determines the worst case range of addresses to which a data
  129.  breakpoint applies, as follows:  if the nominal breakpoint address is addr, the
  130.  actual range of addresses breakpointed may, in the worst case, be
  131.     [(addr & ~(breakpointResolution - 1)) ..
  132.             (addr & ~(breakpointResolution - 1)) + breakpointResolution - 1].
  133. */
  134. typedef SOMLargeStruct            DSDataBreakpointInformation; /* Derived from a struct of 8 bytes in size */
  135.  
  136. typedef OpaquePtr                DSDataBreakpointInformationPtr; /* Substituted OpaquePtr for ``DSDataBreakpointInformation*'' */
  137.  
  138. /*
  139.  The access types to which a data breakpoint should apply.  Use
  140.  kDSBreakDisable to clear a data breakpoint.  Note that the implementation
  141.  may not support breakpointing read and write accesses independently; in
  142.  that case specifying either option will have the same effect (break on
  143.  any access).
  144. */
  145. typedef OptionBits                DSDataBreakpointOptions;
  146.  
  147. /*
  148.  Debugger Services functions
  149.  Register the debugger.  Returns kernelIDErr if there is already a debugger
  150.  registered.
  151. */
  152. /*
  153.  Unregister the debugger.  This is also done automatically by the kernel if
  154.  the debugger terminates.
  155. */
  156. /* Wait specified amount of time for an exception message from the kernel.*/
  157. /*
  158.  Resume execution of a task halted by an earlier exception.  If exceptionReturnStatus
  159.  is noErr, resume the task, else propagate the exception.  If the propagated exception
  160.  remains unhandled, a second exception notification will be generated.
  161. */
  162. /* Make the specified task(s) ineligible for execution, until released by DSReleaseTasks.*/
  163. /* Make the specified held task(s) eligible again for execution.*/
  164. /*
  165.  Get the scheduler state for a task.   The task may be in a software interrupt or in
  166.  normal execution; if normal, state->swiState.kernelState will be kInactiveState.  In
  167.  either case, the appropriate state->taskState.kernelState or state->swiState.kernelState
  168.  will be kRunState if the task is running, and if so the corresponding PC and SP values
  169.  are invalid and will be returned as zero.  If the task is blocked in normal execution
  170.  then state->taskState.PC and state->taskState.SP will reflect the PC and SP at the time
  171.  of the system call which caused the task to block.  Similarly, if the task is blocked
  172.  in a software interrupt, hence not running, then state->swiState.PC and state->swiState.SP
  173.  will be nonzero.
  174. */
  175. /*
  176.  Create a write access right to the page for logical address dstAddr in address
  177.  space addrSpaceID.  This makes the page physically resident and prevents subsequent
  178.  reads or writes of the page from or to backing storage.  The access right is returned
  179.  in memAccessID.
  180. */
  181. /*
  182.  Modify the memory to which an access right has been obtained.  memAccessID is the access
  183.  right, dstAddr is the target address, srcDataPtr points to the source data to be written,
  184.  and numBytes is the size of the write.  The range [dstAddr..dstAddr + numBytes - 1] must lie
  185.  entirely within the page specified by the access right.  If the destination memory is code,
  186.  processor caches will be synchronized appropriately.
  187. */
  188. /*
  189.  Delete an access right and allow normal backing storage activity for that page.  memAccessID
  190.  is the access right.  Note: changes to the page up to this point will NOT be written to
  191.  backing storage.
  192. */
  193. /*
  194.  Read memory.  srcAddr is the address to read from, addrSpaceID specifies the address space,
  195.  dstDataPtr points to the debugger buffer into which to copy the data, and numBytes is the
  196.  size of the read.
  197. */
  198. /*
  199.  Set a data breakpoint.  addrSpaceID specifies the address space, which may or may not be
  200.  used.  breakAddr is the logical address to break on.  numBytes is a hint as to the range
  201.  of addresses to break on.  The address range [breakAddr .. (breakAddr + numBytes -1)] must
  202.  lie within the worst case data breakpoint resolution which the implmentation supports, as
  203.  determined via DSGetDataBreakpointInformation.  A data breakpoint hit will result in a
  204.  memory access exception of type kDataBreakpointException.  The implementation may cause
  205.  excess exceptions which will have to be filtered out by the debugger, e.g. breakpoints
  206.  may occur in the wrong address space or on an address which is outside the range specified
  207.  but which lies within the resolution range supported by the implementation.  To "fix up"
  208.  a memory reference which triggered a data breakpoint exception without removing the
  209.  data breakpoint, use DSReadMemory or DSWriteMemory.  Data breakpoints may be disallowed
  210.  on certain addresses which are used by system code; DSSetDataBreakpoint will return
  211.  kernelInUseErr for such addresses.
  212. */
  213. /*
  214.  Get information about data breakpoint support.  Returns the number of breakpoints available in
  215.  the current implementation and the worst case address resolution of a data breakpoint.
  216. */
  217. #endif
  218.  
  219. #endif /* __SOMIDL__ */
  220.  
  221. #endif /* __DEBUGGERSUPPORT_IDL__ */
  222.  
  223.